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where n of [nt] means the nroff formatter version, and t means the troff formatter version. The 
noncompactible segment must be produced manually by using the editor. Using the mac package as an example, 
the following could be used to install the nroff formatter noncompactible segment: 


$ ed mac 
/*\.co$/+,$w /usr/lib/macros/ucmp.n.mac 


4. TROFF Tutorial 
4.1 Overview 


An important rule of using the troff formatter is to use it through an intermediary. In many ways the troff 
formatter resembles an assembly language, remarkably powerful and flexible, but nonetheless such that many 
operations must be specified at a level of detail and in a form that is too difficult for most people to use effective- 
ly. 


There are programs that provide an interface to the troff formatter for the majority of users for two special 
applications. 


e The eqn program provides an easy to learn language for typesetting mathematics. The user does not 
need to know the troff formatter to typeset mathematics. 


e The tbl program provides the same convenience for producing tables of arbitrary complexity. 


For producing text that may contain mathematics or tables, there are a number of macro packages that 
define formatting rules and operations for specific styles of documents and reduce the amount of direct contact 
with the troff formatter. In particular, the Memorandum Macros (MM) package provides most of the facilities 
needed for a wide range of document preparation. There are also packages for viewgraphs and other special ap- 
plications. These packages are easier to use than the troff formatter once the user gets beyond the most trivial 
operations. They should be considered first. 


In the few cases where existing packages do not accomplish the job, the solution is not to write an entirely 
new set of troff instructions from scratch but to make small changes to adapt packages that already exist. In 
accordance with this philosophy, the part of the troff formatter described here is only a small part of the whole, 
although it tries to concentrate on the more useful parts. The emphasis is on doing simple things and making 
incremental changes to what already exists. The troff formatter described is the C language version running 
on the UNIX operating system at Murray Hill. 


To use the troff formatter, the actual text must be prepared plus some information that describes how it 
is to be printed. Text and formatting information are intimately intertwined. Most commands to the troff 
formatter are placed on a line separate from the text itself, one command per line beginning with a period. For 
example 


Some text. 
ps 14 
Some more text. 


will change the point size of the letters being printed to 14 point (one point is 1/72 of an inch), 


Occasionally, something special occurs in the middle of a line, such as an exponent. The formula for the area 
of a circle is typed as follows: 


Area = \(*p\fIr\fR\\s8\u2\d\s0 


The backslash character (\) is used to introduce troff commands and special characters within a line of text. 


* 
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4.2 Point Sizes and Line Spacing 


The .ps request sets the point size. Since one point is 1/72 inch, 6-point characters are 1/12 inch high, and 
36-point characters are % inch high. There are 15 point sizes—6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 
36 point. Point size is rounded up to the next valid value, with a maximum of 36, if the number following the 
.ps request is not a legal value. 


If no number follows the .ps request, point size reverts to the previous value. The troff processor begins 
with point size 10. Point size can also be changed in the middle of a line or a word with a \s escape sequence. 
The \s sequence should be followed by a legal point size. The \sO sequence causes the size to revert to its previ- 
ous value. The \s1011 sequence can be understood correctly as “size 10, followed by an 11”. Caution should 
be exercised with similar constructions. 


Relative size changes are also legal and useful: 
\s-2UNCLE\s+2 


temporarily decreases the size by two points, then restores it. Relative size changes have the advantage that 
the size difference is independent of the starting size of the document. The amount of the relative change is re- 
stricted to a single digit. 


Another parameter that determines what the type looks like is the spacing between lines. It is set indepen- 
dently of the point size. Vertical spacing is measured from the bottom of one line to the bottom of the next. The 
command to control vertical spacing is .vs. For running text, it is usually best to set the vertical spacing about 
20 percent larger than the character size. For example, a usable combination would be 


-ps 9 
.vs llp 


Vertical spacing is partly a matter of taste, depending on how much text is to be squeezed into a given space, 
and partly a matter of traditional printing style. By default, the troff formatter uses a point size of 10 and a 
vertical spacing of 12. When .vs is used without arguments, vertical spacing reverts to the previous value. 


The .sp request is used to get extra vertical space. Used alone, it gives one extra blank line (whatever ws 
is set). Since that may be more or less than desired, .sp can be followed by information about how much space 
is wanted. For instance: 


sp 1.51 means “a space of 1.5 inches” (most troff processor installations understand decimal frae- 
tions) 

Sp 2i means “two inches of vertical space” 

sp 2p means “two points of vertical space” 

Sp 2 or .sp 2v means “two vertical spaces” (two of whatever .vs is set). 


These same scale factors can be used after the .vs request to define line spacing. Scale factors can be used after 
most commands that deal with physical dimensions. 


All size numbers are converted internally to machine units, which are 1/432 inch (1/6 point). For most pur- 
poses, this is enough resolution to provide good accuracy of representation. The situation is not quite so good 
vertically, where resolution is 1/144 inch (4 point). 
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4.3 Fonts and Special Characters 


The troff processor and the typesetter allow four different fonts at one time. Normally, three fonts (Times 
Roman, Times Italic, and Times Bold) and one collection of special characters are permanently mounted. The 
Greek, mathematical symbols, and miscellany of the special font are listed in Table 3.D. 


The troff processor prints in Roman unless otherwise commanded. To change the font, the .ft request is 
used: 


{t B switch to bold font. 

ft I switch to italics font. 
ft R switch to Roman font. 
ft P return to previous font. 
ft return to previous font. 


The underline request (.ul) causes the next input line to print in italics. It can be followed by a count to indi- 
cate that more than one line is to be italicized. 


Fonts can also be changed within a line or word with the \f in-line sequences. For instance 
bold face text 
is produced by 
\fBbold\fIface\fR text 
If it is desired to do this so the previous font is left undisturbed, extra \fP sequences should be inserted: 
\fBbold\fP\flface\fP\fR text\fP 


Since only the immediately previous font is remembered, the previous font must be restored after each change 
or it will be lost. The same is true of .ps and .vs when used without an argument. 


There are other fonts available besides the standard set, although only four can be used at any given time. 
The .fp request tells the troff formatter what fonts are actually mounted on the typesetter. For example: 


fp 3H 


says that the Helvetica font is mounted on position 3. A list of fonts and what they look like are shown in Fig. 
3.1. Appropriate .fp requests should appear at the beginning of a document if standard fonts are not used. 


It is possible to make a document relatively independent of the actual fonts used to print it by using font 
numbers instead of names. For example: \f3 and .ft3 mean “whatever font is mounted at position 3”. Normal 
settings are Roman font on 1, italic on 2, bold on 3, and special on 4, 


There is also a way to get synthetic bold fonts by overstriking letters with a slight offset. The .bd request 
addresses this function. 


Special characters have 4-character input names beginning with \( and may be inserted anywhere in the 
text. In particular, Greek letters are all of the form \(*—, where — is an uppercase or lowercase Roman font 
letter reminiscent of the Greek. A list of these special names is given in Table 3.D. 


Some characters are automatically translated into others: grave (*) and acute (-) accents become open and 
close single quotation marks. Similarly, a typed minus sign becomes a hyphen. The \~ input will print an ex- 
plicit minus sign. A \e entry causes a backslash to be printed. 
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4.4 Indents and Line Lengths 


The troff processor starts with.a line length of 6.5 inches, which is too wide for 8-% inch by 11-inch paper. 
The .ll request resets the line length. For example: 


ll 61 


As with the .sp request, the actual length can be specified in several ways; inches are probably the most intu- 
itive. The maximum line length provided by the typesetter is 7.5 inches. To use the full width, the default physi- 
cal left margin (page offset) must be reset. This is done by the .po request. The margin is normally slightly less 
than 1 inch from the left edge of the paper. The .po 0 request sets the offset as far to the left as it will go. 


The indent request (.in) causes the left margin to be indented by some specified amount from the page offset. 
If .in is used to move the left margin to the right and the .Il is used to move the right margin to the left, offset 
blocks of text are obtained. As an example 


An 0.51 

ll -0.5i 

text to be set into a block 
ll +0.5i 

in —0.5i 


will create a block that looks like: 


A clergyman at Cambridge preached a sermon which one of his auditors commended. “Yes,” 
said a gentleman to whom it was mentioned, “it was a good sermon, but he stole it.” This was told 
to the preacher. He resented it, and called on the gentleman to retract what he had said. “I am 
not,” replied the aggressor, “very apt to retract my words, but in this instance I will. I said, you 
had stolen the sermon; I find I was wrong; for on returning home, and referring to the book 
whence I thought it was taken, I found it there.” 


The use of + and — changes the previous setting by the specified amount rather than just overriding it. The 
distinction is quite important: 


e .l] +1i makes lines 1 inch longer 
e .ll 1i makes lines 1 inch long. 
With the .in, .ll, and .po requests, the previous value is used if no argument is specified. 


The .ti request is used to temporarily indent a single line. For example, all paragraphs in this manual effec- 
tively begin with the .ti 3 request. Since no units are specified, the line is indented three ems by default. The 
default unit for .ti, as for most horizontally oriented requests (.Il, .in, .po), is ems. An em is roughly the width 
of the letter m in the current point size. Precisely, an em in size pis ppoints. Although inches are usually clearer 
than ems to people who do not set type for a living, ems have a place: they are a measure of size that is propor- 
tional to the current point size. The ems unit is used to make text that keeps its proportions regardless of point 
size. The ems can be specified as scale factors directly, as in .ti 2.5m. 
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Lines can be indented negatively if the indent is already positive: 
ti —.3i 
causes the next line to be moved back 3/10 of an inch. 
To make a decorative initial capital that is three lines high: 
e The whole paragraph is indented. 
e The initial character is moved back with the .ti request. 


e The initial character is made bigger (e.g., \s36N\s0) and moved down from its normal position (see 
Part 6). 


4.5 Tabs 


Tabs (the ASCII horizontal tab character) can be used to produce output in columns or to set the horizon- 
tal position of output. Typically, tabs are used only in unfilled text. Tab stops are set by default every half inch 
from the current indent but can be changed by the .ta request. Tab stops are set every inch, for example, with 
the following entry: 


ta 1i 2i 3i 4i 5i 61 


Tab stops are left justified (as on a typewriter), so lining up columns of right-justified numbers can be a 
problem. If there are many numbers or if a table layout is needed, the tbl program is available (Section 4). 


A handful of numeric columns can be done by preceding every number with enough blanks to make it line 
up when typed. For instance: 


nf 
tacky Siest 
Itab tab 3 


40tab 50tab 60 
700tab 800tab 900 
fi 


Each leading blank is a \O string. This is a character that does not print but has the same width as a digit. 
When printed it produces: 


i! 2 3 
40. 50 60 
700 800 900 
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It is also possible to fill up tabbed-over space with some character other than blanks by setting the tab 
replacement character with the .te request: 


ta 1.51 2.51 
te \(ru \' (ru is _) 
Name tab Age tab 


produces 


Namie soon Age 


To reset the tab replacement character to a blank, the .te request (with no argument) is used. Lines can also 
be drawn with the \l escape sequence as described in paragraph 4.6.4. 


The troff processor provides a general mechanism called “fields” for setting up complicated columns. This 
is used by the tbl program. 


4.6 Local Motions 


The troff processor provides a number of escape sequences for placing characters of any size at any place. 
They can be used to draw special characters or to tune the output for a particular appearance. Most of these 
sequences are straightforward but messy to read and tough to type correctly. 


4.6.1 Vertical Motions 


If the eqn program is not used, subscripts and superscripts are most easily done with the half-line local 
motions \u and \d sequences. To go back up the page half a point size, a \u is inserted at the desired place; 
to go down half a point size, a \d is inserted. The \u and \d should always be used in pairs. Since \u and \ 
d refer to the current point size, they should either be both inside or both outside the size changes. Otherwise, 
an unbalanced vertical motion will result. 


Sometimes the space given by \u and \d is not the right amount. The \v sequence can be used to request 
an arbitrary amount of vertical motion. The in-line sequence \v’ N causes motion up or down the page by the 
amount specified in N. For example, to move the character “P” down, the following would apply: 


in +0.61 (indent paragraph) 
03) (shorten lines) 
at —0:31 (move N back) 


\v’2’\s36N\s0\v’—2’ott met Shott, Nott 
shot at Shott.... 


A minus sign causes upward motion, while no sign or a plus sign means down the page. Thus \v’~ 2’ causes an 
upward vertical motion of two line spaces. 


There are many other ways to specify the amount of motion 


\v'0.A7 

\v'3p’ 

\v’—0.5m’ 
etc. are all legal. The scale specifier i, p, or m goes inside the quotes. Any character can be used in place of the 
quotes. This is true of all other troff formatter commands and sequences described in this section. 


Since the troff formatter does not take within-the-line vertical motions into account when figuring where 
it is on the page, output lines can have unexpected positions if the left and right ends are not at the same vertical 
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position. Thus \v, like \u and \d, should always balance upward vertical motion in a line with the same amount 
in the downward direction. 

4.6.2 Horizontal Motions 


Arbitrary horizontal motions are also available, \h is analogous to \v, except that the default scale factor 
is ems instead of line spaces. As an example, 


\h’-0.17 


causes a backwards motion of a tenth of an inch. In a practical situation, when printing the mathematical sym- 
bol > >, the default spacing is too wide, so eqn replaces this by 


>\h’—0.38m’> 
to produce >>. 

Frequently, \h is used with the “width function” \w to generate motions equal to the width of some charac- 
ter string. The construction \w’thing’ is a number equal to the width of thing in machine units (1/482 inch). 
All troff formatter computations are ultimately done in these units. To move horizontally, the width of an xfR, 
\h’ \w’x’w’ is used. Since the default scale factor for all horizontal dimensions is m (ems), u (machine units) 
must be used, or the motion produced will be too large. Nested quotes are acceptable to the troff formatter as 
long as none are omitted. An example of this kind of construction would be to print the string .sp by overstriking 
with a slight offset. The following example puts out .sp, moves left by the width of .sp, moves right one unit, 
and prints .sp again: 

.sp\h’—\w’.sp’u’\h’1lu’.sp 
Part 11 describes a way of avoiding typing so much input for each command name. 


There are several special-purpose troff formatter sequences for local motion: 


e The \O is an unpaddable (never widened or split across a line-by-line justification and filling) white 
space of the same width as a digit. 


e The \<space> is an unpaddable character the width of a space. 

e The \! is 1/6 the width of a space. 

e@ The \~* is 1/12 the width of a space. 

e The \& has zero width and is useful in entering a text line that would otherwise begin with a .. 


e The \o sequence causes up to nine characters to be overstruck, centered on the widest. This is for accents 
such as: 


syst\o" e\(ga" me t\o" e\(aa" I\o" e\(aa" phonique 
which produces 
systeme téléphonique 


The accents \(ga and \(aa (\‘ and \’) are just one character to the troff formatter. 
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4.6.3 Overstrikes 


Overstrikes can be made with another special convention, \z, the zero-motion sequence. Normal horizontal 
motion is suppressed with the \zx after printing the single character x, so another character can be laid on 
top of it. Although sizes can be changed within \o, characters are centered on the widest, and there can be no 
horizontal or vertical motions. The \z may be the only way to get what is needed. 


A more ornate overstrike is given by the bracketing function \b, which piles up characters vertically, cen- 
tered on the current base line. Thus big brackets are obtained by constructing them with piled-up smaller pieces. 


4.6.4 Drawing Lines 

A convenient facility for drawing horizontal and vertical lines of arbitrary length with arbitrary characters 
is provided by the troff formatter. A 1-inch long line is printed with a \I’1i’ sequence. The length can be fol- 
lowed by the character to use if the _ is not appropriate. The \I’0.5i.’ sequence draws a %-inch line of dots. 
Escape sequence \L is analogous, except that it draws a vertical instead of a horizontal line. The document titled 
“Table Formatting Program” describes other ways of providing horizontal and vertical lines. 
4.7 Strings 

If a paper contains a large number of occurrences of an acute accent over a letter e, typing \o"e\’" for 
each é would be a nuisance. Fortunately, the troff formatter provides a way to store an arbitrary collection 
of text in a “string”, and thereafter use the string name as a shorthand for its contents. Strings are one of sev- 
eral troff formatter mechanisms whose judicious use permits typing a document with less effort and organizing 
it so that extensive format changes can be made with few editing changes. 


A reference to a string is replaced by whatever text as defined the string. Strings are defined with the .ds 
request. The line 


.ds e \o" e\’" 
defines the string e to have the value \o"e\’" . 


String names may be either 1 or 2 characters long. They are referred to by \*x for 1-character names or 
\*(xy for 2-character names. Thus, to get 


téléphone 
given the definition of the string e as above, 
t\*el\*ephone 
is the input. 
If a string must begin with blanks, it is defined as 
.ds xx " text 


The double quote signals the beginning of the definition. There is no trailing quote; the end of the line terminates 
the string. 


A string may be several lines long. If the troff formatter encounters a \ at the end of any line, it is thrown 
away and the next line is added to the current one. A long string can be made by ending each line except the 
last with a backslash. 
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ds xx this \ 
is a very \ 
long string 


Strings may be defined in terms of other strings or even in terms of themselves. 
4.8 Introduction to Macros 


In its simplest form, a macro is a shorthand notation similiar to a string. For instance, if every paragraph 
is to start in exactly the same way, with a space and a temporary indent of two ems, the following requests would 
perform the operation: 


sp 
ti +2m 


To save typing these requests every time used, they could be collapsed into one shorthand line, such as a troff 
command, .PP. The .PP is called a macro. The way to tell the troff formatter what .PP means is to define it 
with the .de request: 


.de PP 
Sp 
ti +2m 


The first line names the macro (.PP in this example). It is in uppercase so it will not conflict with any name 
that the troff formatter might already know about. The last line (..) marks the end of the definition. In between 
is the text which is ingerted whenever the troff formatter sees the .PP macro call. A macro can contain any 
mixture of text and formatting requests. 


The definition of a macro has to precede its first use; undefined macros are ignored. Names are restricted 
to one or two characters. 


Using macros for commonly occurring sequences of requests is important since it saves typing and makes 
later changes easier. If it is decided that in producing a document the paragraph indent is too small, the vertical 
space is too large, and Roman font should be forced, only the definition of .PP needs to be changed to read 


.de PP \" paragraph macro 
sp 2p 

ti +3m 

ftR 


The change takes effect everywhere .PP is used and is easier than changing commands throughout the whole 
document. 


A troff formatter escape sequence that causes the rest of the line to be ignored is \" . It is used to add com- 
ments to the macro definition (a wise idea once definitions get complicated). 


Another example of macros that start and end a block of offset, unfilled text is 


de OS \" start indented block 


Sp 
nf 
in +0.31 
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Copy to 

John Doe 
Richard Roberts 
Stanley Smith 


In this example, the indention used is .in +0.3i instead of .in 0.3i. This permits the nesting of the .OS and .OE 
€ macros to get blocks within blocks. 


Should the amount of indention be changed at a later date, it is necessary to change only the definitions 
of .OS and .OE, not individual requests throughout the whole paper. 


4.9 Titles, Pages, and Numbering 


Titles, pages, and numbering is a complicated area where nothing is done automatically. Of necessity, some 
of this section is a cookbook to be copied literally until some experience is obtained. 


To get a title at the top of each page, such as: 
left top center top right top 


& it was possible on an older system (roff) to get headers and footers automatically on every page with the follow- 
ing: 


-he ’left top’center top’right top’ 
fo ‘left bottom’center bottom’right bottom’ 


This does not work in the troff formatter. Instead, specifications must be provided: 
e What to do at and around the title line 
e When to print the title 


e What the actual title is. 


The .NP macro (new page) is defined to process titles at the end of one page and the beginning of the next: 


.de NP 

*bp 

*sp 0.51 

.tl left top’center top’right top’ 
’sp 0.31 


These requests are explained as follows: 
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.de OE \"" end indented block 

0) | 

in —0.3i 

The .OS and .OE macros could be used before and after text to provide the following effect: 

e The ’bp (begin page) command causes a skip to the top-of-page. 
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e The ’sp 0.5i command will space down '4 inch. 
e The .tl command prints the title. 
e The ’sp 0.31 provides another 0.3 inch space. 


The reason that the ’bp and ’sp commands are used instead of the .bp and .sp requests is that the .sp and 
-bp cause a break to take place. This means that all the input text collected but not yet printed is flushed out 
as soon as possible, and the next input line is guaranteed to start a new line of output. Had .bp been used in 
the .NP macro, a break in the middle of the current output line would occur when a new page is started. The 
effect would be to print the left-over part of that line at the top of the page, followed by the next input line on 
a new output line. This is not desired. Using’ instead of . for a command tells the troff formatter that no break 
is to take place. The output line currently being filled should not be forced out before the space or new page. 


The list of requests that cause a break is short and natural: 
oe br te: - Sane ep I 


Other requests cause no break, regardless of whether a. or a’ is used. If a break is really needed, a .br request 
at the appropriate place will provide it. 


To ask for .NP at the bottom of each page, a statement like “when the text is within an inch of the bottom 
of the page, start the processing for a new page” is used. This is done with the .wh request. For example: 


wh -li NP 


No. character is used before NP since it is simply the name of a macro and not a macro call. The minus sign 
means “measure up from the bottom of the page”, so —1i means 1 inch from the bottom. 


The .wh request appears in the input outside the definition of .NP. Typically, the input would be 


.de NP 
--- body of macro 


wh =i NP 


As text is actually being output, the troff formatter keeps track of its vertical position on the page; and 
after a line is printed within 1 inch from the bottom, the .NP macro is activated. 


e The .wh request sets a trap at the specified place. 
e The trap is sprung when that point is passed. 


The .NP macro causes a skip to the top of the next page (that is what the ’bp was for) and prints the title with 
appropriate margins. 


Something to beware of when changing fonts or point sizes is crossing a page boundary in an unexpected 
font or size. Titles come out in the size and font most recently specified instead of what was intended. The length 
of a title is independent of the current line length, so titles will come out at the default length of 6.5 inches unless 
changed. Changing title length is done with the .lt request. 


There are several ways to fix the problems of point sizes and fonts in titles. The .NP macro can be changed 
to set the proper size and font for the title, and then restore the previous values, like this: 


.de NP 
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— 
sp 0.51 

ft \" set title font to Roman 
.ps 10 \" set size to 10 point 

lt 6i \" set length to 6 inches 
tl ‘left’center’right’ 

.ps \" revert to previous size 
ft? \" and to previous font 


’sp 0.31 


This version of .NP does not work if the fields in the .t] request contain size or font changes. To cope with 
that contingency requires the troff formatter “environment” mechanism discussed in Part 13. 


To get a footer at the bottom of a page, the NP macro should be modified. One option is to have the .NP 
macro do some processing before the *bp request. Another option is to split the macro into a footer macro (in- 
voked at the bottom margin) and a header macro (invoked at the top of page), 

Output page numbers are computed automatically as each page is produced ( starting at 1), but no numbers 
are printed unless explicitly requested. To get page numbers printed, the % character should be included in the 
.tl request at the position where the number is to appear. For example: 


tl a % a 


centers the page number inside hyphens. The page number can be set at any time with either a .bp n request 
(which immediately starts a new page numbered n) or with .pn n (which sets the page number for the next page 
but does not cause a skip to the new page). The .bp +n sets the page number to n more than its current value. 
The .bp request without an argument means .bp +1. 


4.10 Number Registers and Arithmetic 


The troff processor has a facility for doing arithmetic and defini ng and using variables with numerie val- 
ues, called number registers. Number registers, like strings and macros, can be useful in setting up a document 
so it is easy to change later. They also serve for any sort of arithmetic computation. 


Like strings, number registers have 1- or 2-character names. They are set by the .nr request and are refer- 
enced anywhere by \nx (1-character name) or \n(xy (2-character name) 


There are quite a few predefined number registers maintained by the troff formatter, among them: 
e % for the current page number 
e ni for the current vertical position on the page 
ry dy, mo, and yr for the current day, month, and year 


e .s and .f for the current size and font (the font is a number from one to four). 


Any of these can be used in computations like any other register, but some, like .s and .f, cannot be changed 
with .nr. 


An example of the use of number registers is in an older macro package where most significant parameters 
are defined in terms of the values of a handful of number registers. These include the point size for text, the 
vertical spacing, and the line and title lengths. To set the point size and vertical spacing, a user may input 
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mr PS 9 
wor VS 11 


The paragraph macro, .PP, is roughly defined as follows: 
.de PP 


-_ps \\n(PS \" reset size 
.vs \\n(VSp —_\"" spacing 


ft R \ tong 
sp 0.5v \" half a line 
ti +3m 


This sets the font to Roman and the point size and line spacing to whatever values are stored in the number 
registers PS and VS. 


The reason for two backslashes is to indicate that a backslash is really meant. When the troff formatter 
originally reads the macro definition, it peels off one backslash to see what is coming next. Two backslashes 
in the definition are required to ensure that a backslash is left in the definition when the macro is used. If only 
one backslash is used, point size and vertical spacing will be frozen at the time the macro is defined, not when 
it is used. 


Protecting by an extra layer of backslashes is needed only for \n, \*, \$, and \ itself. Things like \s, \f, 
\h, \v, etc. do not need an extra backslash since they are converted by the troff formatter to an internal code 
immediately upon detection. 

Arithmetic expressions can appear anywhere that a number is expected. As an example: 


nr PS \\n(PS-2 


decrements PS by 2. Expressions can use the arithmetic operators +, —, *, /, % (mod), the relational operators 
>, >=, <, <=, =, != (not equal), and parentheses. 


So far, the arithmetic has been straightforward; more complicated things are tricky. 


e Number registers hold only integers. In the troff formatter, arithmetic uses truncating integer division 
just like Fortran. 


e Inthe absence of parentheses, evaluation is done left-to-right without any operator precedence includ- 
ing relational operators. Thus: 


443/13 
becomes —1. 
Number registers can occur anywhere in an expression and so can scale indicators like p, i, m, etc. (but no spac- 
es). Although integer division causes truncation, each number and its scale indicator is converted to machine 
units (1/432 inch) before any arithmetic is done, so 1i/2u evaluates to 0.5i correctly, 
The scale indicator u often has to appear when least expected, in particular when arithmetic is being done 


in a context that implies horizontal or vertical dimensions. For example, .l 7/2i is not 3-2 inches. Instead, it 
is really 7 ems/2 inches. When translated into machine units, it becomes 0 (this is because the default units for 


Page 86 


6/82 ISSUE 1 DOCUMENT PROCESSING GUIDE 


horizontal parameters [like .ll] are ems). Another incorrect try is .ll 7i/2. The 2 is 2 ems, so 7i/2 is small, al- 
though not 0. The .1l 7i/2u must be used. A safe rule is to attach a scale indicator to every number, even con- 
stants. 


For arithmetic done within a nr re there is no implication of horizontal or vertical dimension, so the 
default units are “units”, and 7i/2 and 7i/2u mean the same thing. Thus: 


nr Il 7i/2 
ll \\n(lu 


accomplishes what is desired as long as the u on the .Il request is included. 
4.11 Macros With Arguments 


Two things are needed to be able to define macros that can change from one use to the next according to 
parameters supplied as arguments: 


1. When the macro is defined, it must be indicated that some parts will be provided as arguments when the 
macro is called. 


2. When the macro is called, the actual arguments to be plugged into the definition must be provided. 


An example would be to define a macro (.SM) that will print its argument two points smaller than the surround- 
ing text. 


.de 5M 
\s—2\\$1\s+2 
The macro call would appear: 
.SM SMALL 
The argument SMALL in this example would then appear two points smaller than the rest of the print. 


Within a macro definition, the symbol \\$n refers to the nth argument with which the macro was called. 
Thus \\$1 is the string to be placed in a smaller point size when .SM is called. 


A slightly more complicated version is the following definition of .SM which permits optional second and 
third arguments that will be printed in the normal size: 


.de SM 
\\$3\s—2\\$1\s+2\\$2 
Arguments not provided when the macro is called are treated as empty. The macro call 
SM ABLE ), 
would appear (with ABLE in smaller type) 
ABLE), 
The macro call 


.SM BAKER ). ( 
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produces the following (with BAKER in smaller print): 
(BAKER). 


It is convenient to reverse the order of arguments because trailing punctuation is much more common than lead- 
ing. The number of arguments that a macro was called with is available in number register .$. 


The macro, .BD, is used to make “bold Roman” for troff formatter command names in text. It combines 
horizontal motions, width computations, and argument rearrangement: 


.de BD 
\&\\$3\f1\\$1\h’—\w \\ $V'u+2u'\\$1\fP\\$2 


The \h and \w escape sequences need no extra backslash. The \& is there in case the argument begins with 
a period. Two backslashes are needed with the \\$n commands to protect one of them when the macro is being 
defined. A second example will make this clearer. A .SH macro can be defined to produce automatically num- 
bered section headings with the title in smaller size bold print. The use is 


SH "Section title ..." 
If the argument to a macro is to contain blanks, it must be surrounded by double quotes. 


The definition of the .SH macro is 


-nr SH 0 \" initialize section number 
.de SH 

sp 0.3i 

ft B 

-nr SH \\n(SH+1 \" increment number 

-ps \\n(PS-1 \" decrease PS number 
\\n(SH.  \\$1 \" title 

-ps \\n(PS \" restore PS 

sp 0.31 


ft R 
The section number is kept in number register SH, which is incremented each time just before use. 
Note: A number register may have the same name as a macro without conflict but a string may not. 
A \\n(SH and \\n(PS was used instead of a \n(SH and \n(PS. Had \n(SH been used, it would have 
yielded the value of the register at the time the macro was defined, not at the time it was used. Similarly, by 
using \\n(PS, the point size at the time the macro was called is obtained. 
An example that does not involve numbers is the .NP. macro (defined earlier) which had the request 
tl ‘left’center’right’ 
The fields could be made into parameters by using instead 
tl \\*(LT\\*(CT\\*(RT? 


The title comes from three strings called LT, CT, and RT. If these are empty, the title will be a blank line. Nor- 
mally, CT would be set with 


ae OP ys 
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to give just the page number between hyphens. A user could supply private definitions for any of the strings. 


4.12 Conditionals 


Suppose it is desired that the .SH macro leave two extra inches of space just before Section 1, but nowhere 
else. The cleanest way to do that is to test inside the .SH macro whether the section number is 1, and add some 
space if it is. The .if command provides the conditional test that can be added just before the heading line is 
output: 


if \\n(SH=1 .sp 2i \" first section only 


The condition after the .if request can be any arithmetic or logical expression. If the condition is logically 
true or arithmetically greater than zero, the rest of the line is treated as if it were text (a request in this case). 
If the condition is false, zero, or negative, the rest of the line is skipped. 


It is possible to do more than one request if a condition is true. For example, if several operations are to 
be done prior to Section 1, the .S1 macro is defined and invoked when Section 1 is almost complete (as deter- 
mined by an .if). 


de S1 
--- processing for section 1 


‘de SH 


if \\n(SH=1 .S1 


An alternate way is to use the extended form of the .if request, e.g.: 


if \\n(SH=1 \{--- processing 
for section 1 ---\} 


The braces, \{ and \}, must occur in the positions shown or unexpected extra lines will be in the output. The 
troff processor also provides an “if-else” construction. 


A condition can be negated by preceding it with !. The same effect as above is obtained (but less clearly) 
by using 


if \\\n(SH>1 .S1 
There are a handful of other conditions that can be tested with .if. For example: 


if e .tl ‘left top’ center top ‘right top’ 
if o .tl ‘left top’ center top ‘right top’ 


gives facing pages different titles, depending on whether the page number is even or odd, when used inside an 
appropriate new page macro. 


Two other conditions are t and n, which tells whether the formatter is troff or nroff: 


if t troff stuff ... 


Page 89 


DOCUMENT PROCESSING GUIDE ISSUE 1 6/82 


if n nroff stuff ... 
String comparisons may be made in a .if request. 


Jif ’stringl’string2’ stuff 


executes the program stuff if string] is the same as string2 The character separating the strings can be any- 
thing reasonable that is not contained in either string. The strings themselves can reference strings with \*, 
arguments with \§, ete. 


4.13 Environments 


There is a potential problem when going across a page boundary: parameters like size and font for a page 
title may be different from those in effect in the text when the page boundary occurs. A general way to deal 
with this and similar situations is provided by the troff formatter. 


There are three environments. Fach has independently selectable versions of many parameters associated 
with processing, including size, font, line and title lengths, fill/no-fill mode, tab stops, and partially collected 
lines. Thus the titling problem may be solved by processing the main text in one environment and titles in an- 
other with its own suitable parameters. 


The .ev n request shifts to environment n (n must be 0, 1, or 2). The .ev request with no argument returns 
to the previous environment. Environment names are maintained in a stack, so calls for different environments 
may be nested and unwound consistently. 


If the main text is processed in environment 0 where the troff formatter begins by default, the new page 
macro, .NP, can then be modified to process titles in environment 1, e.g. 


.de NP 

ev il \" shift to new environment 
lt 61 \" set parameters here 

ft R 

._ps 10 


--- any other processing 
eV \" return to previous environment 


It is also possible to initialize the parameters for an environment outside the .NP macro, but the version shown 
keeps all the processing in one place and is easier to understand and change. 


4.14 Diversions 


There are numerous occasions in page layout when it is necessary to store some text for a period of time 
without actually printing it. Footnotes are the most obvious example. Text of the footnote usually appears in 
the input well before the place on the page is reached where it is to be printed. The place where it is output nor- 
mally depends upon the magnitude of the footnote. This implies that there must he a way to process the footnote, 
at least enough to decide its size without printing it. 


A mechanism called a diversion is provided by the troff formatter for doing this processing. Any part of 
the output may be diverted into a macro instead of being printed; and at some convenient time, the macro may 
be put back into the input. 


The .di xy request begins a diversion. All subsequent output is collected into the macro xy until the .di 
request with no arguments is encountered. This terminates the diversion. Processed text is available at any time 
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thereafter by giving the .xy request. The vertical size of the last finished diversion is contained in the built-in 
number register dn. For instance, to implement a keep-release operation so that text between the macros .KS 
and .KE will not be split across a page boundary (as for a figure or table), the following applies: 


e When a.KS is encountered, the output is diverted to determine its size. 


e When a.KE is encountered and if the diverted text will fit on the current page, it is printed there. If 
the diverted text does not fit on the current page, it is printed at the top of the next page. 


The definitions of the .KS and .KE macros are as follows: 


de KS \" start keep 


-br \" start fresh line 

ev 1 \" collect in new environment 
fi \" make it filled text 

dT EX \" collect in XX 

de KE \" end keep 

.br \" get last partial line 

di \" end diversion 

Af \\n(dn>=\\n(.t .bp \"" bp if does not fit 

nf \" bring it back in no-fill 

XX \" text 

eV \" return to normal environment 


The number register nl indicates the current position on the output page. Since output was being diverted, 
it remains at its value when the diversion started. The dn register contains the amount of text in the diversion. 
The distance to the next trap is in the built-in register .t. It is assumed that the next trap is at the bottom margin 
of the page. If the diversion is large enough to go past the trap, the .if is satisfied; and a .bp request is issued. 
In either case, the diverted output is brought back with .XX. It is essential to bring it back in no-fill mode so 
the troff formatter will do no further processing on it. 


This is not the most general keep-release operation nor is it robust in the face of all conceivable inputs. It 
would require more space than available to display it in full generality. This manual is not intended to teach 
everything about diversions, but to sketch out enough so that existing macro packages can be read with some 
comprehension. 


5. NROFF/TROFF Tutorial Examples 


Although the nroff and troff formatters have by design a syntax reminiscent of earlier text processors 
with the intent of easing their use, it is usually necessary to prepare at least a small set of macro definitions 
to describe most documents. Such common formatting needs such as page margins and footnotes are deliber- 
ately not built into the nroff and troff formatters. Instead, the macro and string definition, number register 
diversion, environment switching, page-position trap, and conditional input mechanisms provide the basis for 
user-defined implementations. 


, 


Examples in the following text are intended to be useful and somewhat realistic but will not necessarily 
cover all relevant contingencies. Explicit numerical parameters are used to make the examples easier to read 
and to illustrate typical values. In many cases, number registers would be used to reduce the number of places 
where numerical information is kept and to concentrate conditional parameter initialization data that depends 
on whether the troff or nroff formatter is being used. 


5.1 Page Margins 


Header and footer macros are defined to describe the top and bottom page margin areas, respectively. A 
trap is planted at page position 0 for the header and at —N(N from the page bottom) for the footer. A simple 
header and footer macro definition is 
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.de hd \" define header 
’sp li 

4 \" end definition — 
.de fo \" define footer 
*bp 

zs \" end definition 
.wh 0 hd 

.wh —li fo 


This example provides blank 1-inch top and bottom margins. The header will occur on the first page, only if 
the definition and trap exist prior to the initial pseudopage transition. In fill mode, the output line that springs 
the footer trap was typically forced out because some part or whole word did not fit on it. If anything in the 
footer and header that follows causes a break, that word or part word will be forced out. In this and other exam- 
ples, requests like bp and sp that normally cause breaks are invoked using the no-break control character (’). 
When the header/footer design contains material requiring independent text processing, the environment may 
be switched to avoid interaction with running text. 


A more realistic example follows: 


in +4 

de hd \" header 

jf t tl ’\(rn’\(rn’ \" troff cut mark 

jf \\n% >1 

’sp 10.5i-1 \" tl base at 0.51 

ce \" centered page number 
.ps \" restore size 

ft \" restore font 

-vs \} \" restore vs 

’sp 11.01 \" space to 1.0i 

ns \" turn on no-space mode 
.de fo \" footer 

ps 10 \" set footer/header size 
ft R \" set font 

.vs 12p \" set base-line spacing 
if \\n%=1 

’sp |\\n(.pu—0.5i-1 \" tl base 0.51 up 

8 bese Sa \" first page number 
"bp 

wh 0 hd 

wh —1i fo 


This example sets the size, font, and base-line spacing parameters for the header/footer material. Parameters 
are restored to their original! values when the header or footer is completed. The material in this case is a page 
number at the bottom of the first page and at the top of the remaining pages. If the troff formatter is used, 
a cut mark is drawn in the form of root-en’s at each margin. The sp’s refer to absolute positions to avoid depen- 
dence on the base-line spacing. Another reason for the sp in the footer is that the footer is invoked by printing 
a line whose vertical spacing swept past the trap position by possibly as much as the base-line spacing. The 
no-space mode is turned on at the end of hd to render ineffective accidental occurrences of sp at the top of the 
running text. 


The above method of restoring size, font, etc. presupposes that such requests (that set previous value) are 
not used in the running text. A better scheme is to save and to restore both the current and previous values 
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as shown for size in the following: 
.de fo 
-nrsl \\n(.s \" current size 
.ps 
nr s2\\n(.s \" previous size 
--- \" rest of footer 


.de hd 

--- \" header stuff 
-ps \\n(s2 \" restore previous size 
ps \\n(sl1 \" restore current size 


Page numbers may be printed in the bottom margin by a separate macro triggered du ring the footer’s page 
ejection: 


de bn \" bottom number 
AL =o \" centered page number 


wh —0.5i—1v bn \" tl base 0.5i up 
5.2 Paragraphs and Headings 


Housekeeping associated with starting a new paragraph should be collected in a paragraph macro that does 
the desired preparagraph spacing, forces the correct font, size, base-line spacing, and indent; checks that enough 
space remains for more than one line; and requests a temporary indent. 


de pg \" paragraph 

-br \" break 

ft R \" force font, 

._ps 10 \" size, 

.vs 12p \" spacing, 

-in 0 \" and indent 

sp 0.4 \" prespace 

ne 1+\\n(.Vu \" want more than 1 line 


ti 0.2 \" temp indent 


The first break in pg will force out any previous partial lines and must occur before the .vs request. The 
forcing of font, size, base-line spacing, and indent is partly a defense against prior error and partly to permit 
things like section heading macros to set parameters only once. The prespacing parameter is suitable for the 
troff formatter; a larger space, at least as big as the output device vertical resolution, would be more suitable 
in the nroff formatter. The choice of remaining space to test for in the .ne is the smallest amount greater than 
one line (the .V is the available vertical resolution). 


A macro to automatically number section headings might look like: 


de sc \" section 

--- \" force font, ete. 
sp 0.4 \" prespace 
ne 2.4+\\n(.Vu \" want 2.4+ lines 
fi 
\\n+8 
nrs0l1 \" initial § 


The usage is se, followed by the section heading text, followed by pg. The .ne test value includes one line of 
heading, 0.4 line in the following pg, and one line of the paragraph text. A word consisting of the next section 
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number and a period is produced to begin the heading line. The format of the number may be set by the .af re- 
quest. 


Another common form is the labeled, indented paragraph where the label protrudes left into the indent 
space. 


.de Ip \" labeled paragraph 
Pg 

in 0.5i \" paragraph indent 
.ta 0.2i 0.51 \" label, paragraph 
ti 0 


\t\\$\1\t\c \" flow into paragraph 


The intended usage is 
lp label 


The Jabel will begin at 0.2 inch and cannot exceed a length of 0.3 inch without intruding into the paragraph. 
The label could be right adjusted against 0.4 inch by setting the tahs instead with .ta 0.4iR 0.5i. The last line 
of Ip ends with \c so that it will become a part of the first line of the text that follows. 


5.3 Multiple Column Output 


The production of multiple column pages requires the footer macro to decide whether it was invoked by 
other than the last column, so that it will begin a new column rather than produce the bottom margin. The 
header can initialize a column register that the footer will increment and test. The following is arranged for 
two columns but is easily modified for more: 


.de hd \" header 

nrcl 01 \" init column count 
-mk \" mark top of text 
.de fo \" footer 

ie \\n+(cl<2 \f{\ 

po +3.4i \" next column; 3.1+0.3 
rt \" back to mark 

-ns \} \" no-space mode 

el \f\ 

-po \\nMu \" restore left margin 
bp \} 

3.11 \" column width 

nr M \\n(.0 \" save left margin 


Typically, a portion of the top of the first page contains full width text; the request for the narrower line 
length, as well as another .mk request, will be made where the 2-column output is to begin. 


5.4 Footnote Processing 


The footnote mechanism is used by imbedding the footnotes in the input text at the point of reference 
demarcated by an initial .fm and a terminal .ef. 
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fn 
Footnote text and control lines. 
.ef 


The following macro definitions cause footnotes to be processed in a separate environment and diverted for 
later printing in the space immediately prior to the bottom margin. There is provision for the case where the 


last collected footnote does not completely fi 
.de hd 


nr’x: 0:1 

nr y 0—\\nb 
.ch fo —\\nbu 
Jf \\n(dn .fz 
.de fo 

nr dn 0 

if \\nx \f{\ 
ev 1 

nf 

.FN 

rm FN 

ie ANN tye 
nr x0 


eV \} 


de fx 

Af \\nx .di fy 
de fn 

.da FN 

ev 1 


jf \\n+x=1 .fs 
fi 


di 
nr y —\\n(dn 
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t in the available space: 


\" header 


\" init footnote count 
\" current footer place 
\" reset footer trap 

\" leftover footnote 


\" footer 
\" zero last diversion size 


\" expand footnotes in evl 
\" retain vertical size 

\" footnotes 

\" delete it 

\" end overflow diversion 
\" disable fx 

\" pop environment 


\" process footnote overflow 
\" divert overflow 


\" start footnote 

\" divert (append) footnote 
\" in environment 1 

\" if first, include separator 
\" fill mode 


\" end footnote 

\" finish output 

\" save spacing 

\" pop ev 

\" end diversion 

\" new footer position 


jf \\nx=1 .nr y —(\\n(.v—-\\nz)\ \" uncertainty correction 


ch fo \\nyu 

if (\\n(nl+1v)>(\\n(.p+\\ny)\ 
ch fo \\n(nlu+1v 

de fs 

NEE: 

.br 

“de fz 

fn 


\" y is negative 
\" it did not fit 
\" separator 


\" 1 inch rule 


\" get leftover footnote 
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nf \" retain vertical size 

fy \" where fx put it 

ef 

nr b 1.0i \" bottom margin size 

.wh 0 hd \" header trap 

wh 12i fo \" footer trap, temp position 
.wh —\\nbu fx \" fx at footer position 

.ch fo —\\nbu \" conceal fx with fo 


e The header macro (hd) initializes a footnote count register x and sets both the current footer trap posi- 
tion register y and the footer trap itself to a nominal position specified in register b. 


e If the register dn indicates a leftover footnote, the fz macro is invoked to reprocess it. 


e The footnote start macro (fn) begins a diversion (append) in environment 1 and increments the footnote 
count register x; if the count is one, the footnote separator macro (fs) is interpolated. The separator 
is kept in a separate macro to permit user redefinition. 


e The footnote end macro (ef) restores the previous environment and ends the diversion after saving spac- 
ing size in register z. 


e Register y is decremented by the size of the footnote which is available in register dn. 


e On the first footnote, register y is further decremented by the difference in vertical base-line spacings 
of the two environments. This prevents late triggering of the footer trap from causing the last line of 
the combined footnotes to overflow. 


e The footer trap is set to the lower of y or the current page position (nl) plus one line to allow for printing 
the reference line. 


e If indicated by x, the footer fo rereads the footnotes from FN in no-fill mode in environment 1 and de- 
letes FN. If the footnotes were too large to fit, the macro fx will be trap-invoked to redivert the overflow 
into fy, and the register dn will later indicate to the header whether or not fy is empty. 


e Both fo and fx macros are planted in the nominal footer trap position in an order that causes fx to be 
concealed unless the fo trap is moved. 


e The footer terminates the overflow diversion (if necessary) and zeros x to disable fx. This is because 
the uncertainty correction, together with a not-too-late triggering of the footer, can result in footnote 
macros finishing before reaching the fx trap. 


5.5 Last Page 


After the last input file has ended, nroff and troff formatters invoke the end macro, if any, and eject the 
remainder of the page. 


.de en \" end-macro 


em en 


During the eject, any traps encountered are processed normally. At the end of this last page, processing termi- 
nates unless a partial line, word, or partial word remains. If it is desired that another page be started, the end- 
macro will deposit a null partial word and effect another last page. 
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